URI

/trustedx-resources/esigp/v1/signatures/{signature_id}

Description

Resource containing information on a signature creation process performed with a mobile device.

Representation

A signature creation process is represented in JSON as follows:

{
    "id" : {string},
    "self" : {string},
    "input" : {InputData},
    "operation_type" : {string},
    "creation_time" : {string},
    "sign_identity_selectors" : [ {
        "labels" : [ {string} ],
        "device_id" : {string},
        "type" : {string},
        "details" : {SignIdentitySelectorDetails}
    } ],
    "device_configuration_url" : {string},
    "domain" : {string},
    "service" : {
        "id" : {string},
        "name" : {string},
        "domain" : {string}
    },
    "result" : {
        "status" : {string},
        "value" : {string},
        "signature_algorithm" : {string},
        "sign_identity" : {SignIdentity},
        "device_type" : {DeviceType}
     },
    "links" : {
        "finish" : {string},
        "fail" : {string},
        "cancel" : {string}
    }
}

Property	Description
`id`	Identifier of the signature creation process.
`self`	Access URL for the resource.
`input`	Information on the data being signed. See `input` Property.
`operation_type`	Type of signature created by the process: Raw signature: `sign:raw` Signature on a transaction: `sign:commitment:transaction` Signature on a document: `sign:commitment:document` Authentication signature on a user: `authentication`
`creation_time`	Time the process started expressed in the `date-time` format of RFC 3339.
`domain`	Domain of the signing user.
`sign_identity_selectors[]`	Signing identity selectors. The signing identity used to create the signature must meet the conditions of one of the specified selectors.
`sign_identity_selectors[].labels[]`	Labels that the signing identity must have according to a selector.
`sign_identity_selectors[].details`	This property is optional and contains conditions that the signing identity must meet for a given selector and that are only applicable to the signing identities of a given type. See the `sign_identity_selectors[].details` property.
`sign_identity_selectors[].type`	This property is optional (required if the `sign_identity_selectors[].details` property is present) and contains the type that the signing identity must be according to a selector.
`sign_identity_selectors[].device_id`	This property is optional (required if the `sign_identity_selectors[].details` property is present) and contains the identifier of the device in which, according to the selector, the private part of the keys associated to the signing identity must be.
`device_configuration_url`	Template of the URL at which the device can access configuration data specific to creating signatures (e.g., the signature policy).
`service`	Service that requests the creation of a signature.
`service.id`	Identifier of the service.
`service.name`	Name of the service.
`service.domain`	Domain of the service.
`result`	Result of the signature creation process. This property only exists in finalized signature creation processes.
`result.status`	Status of the finalized signature creation process (`finished`, `failed` or `canceled`): `finished`: The process has finalized after having successfully created the signature. `failed`: The process has terminated without being able to create the signature because an error occurred. `canceled`: The process terminated without a signature having been created because it was canceled.
`result.value`	Value returned by the signature creation process. This value depends on the final status of the process: If the process ended with the `finished` status: the signature created encoded in base64. If the process ended with the `failed` status: information on the error that occurred (there may not be any information). If the process ended with the `canceled` status: information on the cancellation that occurred (there may not be any information).
`result.signature_algorithm`	Signature algorithm used in the process (`rsa-sha1`, `rsa-sha256`, `rsa-sha384`, `rsa-sha512`, `ecdsa-sha1`, `ecdsa-sha256`, `ecdsa-sha384` and `ecdsa-sha512`).
`result.sign_identity`	Signing Identity used (applied) in the process.
`result.device_type`	Information on the type of device used in the process. This property only exists in signature creation processes that end successfully (`finished`). See the `result.device_type` property.
`links`	URLs for ending the signature process. Only devices containing the signing identities selected by the selectors can access these URLs.
`links.finish`	URL for finalizing the signature process and putting the value of the signature generated in `result.value` and the value `finished` in `result.status`.
`links.fail`	URL for ending the signature process and putting the error information in `result.value` and the value `failed` in `result.status`.
`links.cancel`	URL for ending the signature process and putting the cancellation information in `result.value` and the value `canceled` in `result.status`. URL for ending the process in the `failed` status. URL that responds to the `PUT` verb. The body will optionally contain error information.

input Property

The representation of the input property depends on the type of signature being created.

Document Signature

When a signature is created on a document, the input property is represented as follows:

{
    "service" : {
        "id" : {string},
        "name" : {string},
        "domain" : {string}
    },
    "digest_url" : {string},
    "digest_value" : {string},
    "digest_algorithm" : {string},
    "document_url" : {string},
    "document_alias" : {string},
    "root_certs" : [ {string} ],
    "document_info" : {
        "html" : {string}
    }
 }

Property	Description
`service`	Client application requesting the creation of a signature.
`service.id`	Identifier of the client application.
`service.name`	Name of the client application.
`service.domain`	Domain of the client application.
`digest_url`	URL for obtaining the hash to be signed encoded in base64 and the hash algorithm used.
`digest_value`	Hash of the document to be signed encoded in base64.
`digest_algorithm`	Algorithm used to calculate the hash of the document (`sha1`, `sha256`, `sha384` and `sha512)`.
`document_url`	URL of the document to be signed.
`document_alias`	Alias of the document to be signed.
`root_certs`	Certificates encoded in base64 of the certification paths of the `digest_url` and `document_url` TLS servers.
`document_info`	Additional information on the document to be signed.
`document_info.html`	HTML encoded in base64 with the information displayed to the user on the document to be signed.

Transaction Signature

When a signature is to be created on a transaction, the input property is represented as follows:

{
    "service" : {
        "id" : {string},
        "name" : {string},
        "domain" : {string}
    },
    "data" : {string},
    "digest_algorithm" : {string}
}

Property	Description
`service`	Client application requesting the confirmation of the transaction.
`service.id`	Identifier of the client application.
`service.name`	Name of the client application.
`service.domain`	Domain of the client application.
`data`	HTML displayed to the user to prompt them to confirm the transaction that contains data on the transaction.
`digest_algorithm`	This property is optional and contains the hash algorithm for creating the signature (`sha1`, `sha256`, `sha384` and `sha512)`. If it is not present, the algorithm used will depend on the type of device with which the signature is created.

Basic Signature

When a basic signature is to be created on data, the input property is represented as follows:

{
    "service" : {
        "id" : {string},
        "name" : {string},
        "domain" : {string}
    },
    "digest_url" : {string},
    "digest_value" : {string},
    "digest_algorithm" : {string},
    "data_info" : {
        "html" : {string}
    },
    "root_certs" : [ {string} ]
}

Property	Description
`service`	Client application requesting the creation of a signature.
`service.id`	Identifier of the client application.
`service.name`	Name of the client application.
`service.domain`	Domain of the client application.
`digest_url`	URL for obtaining the hash to be signed encoded in base64 and the hash algorithm used.
`digest_value`	Hash of the data to be signed encoded in base64.
`digest_algorithm`	Algorithm used to calculate the hash of the data (sha1, sha256, sha384 and sha512).
`data_info`	Information on the data to be signed.
`data_info.html`	HTML encoded in base64 with the information displayed to the user on the data to be signed.
`root_certs`	Certificates encoded in base64 of the certification paths of the digest_url TLS server.

sign_identity_selectors[].details Property

The sign_identity_selectors[].details property contains criteria for selecting signing identities that are only applicable to the signing identities of a given type. Therefore, its representation depends on the signing identity type on which the selection is to be made.

pki:x509 type signing identity.

When a pki_x509 type signing identity is selected, the sign_identity_selectors[].details property is represented as follows:

{
    "certificate" : "<certificate base64 encoded>"
}

Property	Description
`certificate`	Certificate associated to a signing identity encoded in base64.

result.device_type Property

The result.device_type property contains information on the type of device used in the process and is represented as follows:

{
    "id" : {string},
    "notifications_service_id" : {string},
    "wakeup_uri_scheme" : {string},
    "verification_policy" : {string},
    "application" : {
        "id" : {string},
        "version" : {string}
    },
    "server_configuration" : {...}
}

Property	Description
`id`	Identifier of the device type.
`notifications_service_id`	Identifier of the notification service used by this type of device.
`wakeup_uri_scheme`	URL scheme that opens the signature application (Mobile ID) in this type of device.
`verification_policy`	Identifier of the verification policy used to validate the authentication signatures and transactions created with this type of device.
`application`	Information on the signature application (Mobile ID) installed in this type of device.
`application.id`	Identifier on the signature application (Mobile ID) installed in this type of device.
`version`	Version on the signature application (Mobile ID) installed in this type of device.
`server_configuration`	Additional configuration of this type of device registered in the server.

Signature Creation Process

URI